home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / borland / bgidriv.zip / BGI.DOC next >
Text File  |  1989-05-31  |  36KB  |  1,038 lines
  1.  
  2.  
  3.               -----------------------------
  4.               The BGI Driver Toolkit
  5.  
  6.  
  7.  
  8.  
  9.               Creating Device Drivers
  10.  
  11.              for the Borland Graphics Interface
  12.            --------------------------------------
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.          Copyright (c) 1988,89 Borland International
  23.  
  24.  
  25.  
  26.  
  27.  
  28.                 Revision 1
  29.  
  30.                    May 15, 1989
  31.  
  32.  
  33.  
  34.  
  35.  
  36. Introduction
  37. =======================
  38.  
  39. The Borland Graphics Interface (BGI) is a fast, compact, and
  40. device-independent software package for graphics development built into the
  41. Turbo Pascal, Turbo C, and Turbo Prolog language products. Device
  42. independence is achieved via loadable device-specific drivers called from a
  43. common Kernel. This document describes basic BGI functionality, as well as
  44. the steps necessary to create new device drivers. Accompanying this
  45. document are files containing sample code and other pertinent information.
  46.  
  47. File Name          File Description
  48.  
  49. BH.C              BGI loader header building program source
  50. BH.EXE              BGI loader header building program
  51. DEVICE.INC          Structure and macro definition file
  52. DEBVECT.ASM          Vector table for sample (DEBUG) driver
  53. DEBUG.C              Main module for sample driver
  54. MAKEFILE          Build file
  55. BUILD.BAT          A batch file for MAKE-phobics
  56.  
  57. BGI Run-time Architecture
  58. =============================
  59.  
  60. Programs produced by Borland languages create graphics via two entities
  61. acting in concert: the generic BGI Kernel and a device-specific driver.
  62. Typically, an application built with a Borland compiler will include
  63. several device driver files on the distribution disk (extension .BGI) so
  64. that the program can run on various types of screens and printers.
  65. Graphics requests (for example, draw line, draw bar, etc.) are sent by the
  66. application to the BGI Kernel, which in turn makes requests of the device
  67. driver to actually manipulate the hardware.
  68.  
  69. A BGI device driver is a binary image; that is, a sequence of bytes without
  70. symbols or other linking information. The driver begins with a short
  71. header, followed by a vector table containing the entry points to the
  72. functions inside. The balance of the driver comprises the code and data
  73. required to manipulate the target graphics hardware.
  74.  
  75. All code and data references in the driver must be near (i.e., small model,
  76. offset only), and the entire driver, both code and data, must fit within
  77. 64K. In use, the device driver can count on its being loaded on a paragraph
  78. boundary. The BGI Kernel uses a register-based calling convention to
  79. communicate with the device driver (described in detail below).
  80.  
  81. BGI Graphics Model
  82. =======================
  83.  
  84. When considering the functions listed here, keep in mind that BGI performs
  85. most drawing operations using an implicit drawing or tracing color (COLOR),
  86. fill color (FILLCOLOR), and pattern (FILLPATTERN).  For example, the
  87. PIESLICE call accepts no pattern or color information, but instead uses the
  88. previously set COLOR value to trace the edge of the slice, and the
  89. previously set FILLCOLOR and FILLPATTERN values for the interior.
  90.  
  91. For efficiency, many operations take place at the position of the current
  92. pointer, or CP. For example, the LINE routine accepts only a single (x,y)
  93. coordinate pair, using the CP as the starting point of the line and the
  94. passed coordinate pair as the ending point. Many functions (LINE, to name
  95. one) affect CP, and the MOVE function can be used to explicitly adjust CP.
  96. The BGI coordinate system places the origin (pixel 0,0) at the upper
  97. left-hand corner of the screen.
  98.  
  99. Header Section
  100. =======================
  101.  
  102. The device header section, which must be at the beginning of the device
  103. driver, is built using macro BGI defined in file DEVICE.INC. The BGI macro
  104. takes the name of the device driver to be built as an argument. For
  105. example, a driver named DEBUG would begin as shown here:
  106.  
  107.   CSEG      SEGMENT PARA PUBLIC 'CODE'    ; any segment naming may be used
  108.       ASSUME  DS:CSEG, CS:CSEG    ; cs=ds
  109.  
  110.       CODESEG
  111.  
  112.       INCLUDE DEVICE.INC        ; include the device.inc file
  113.       BGI      DEBUG            ; declare the device header section
  114.  
  115. The device header section declares a special entry point known as EMULATE.
  116. If the action of a device driver vector is not supported by the hardware of
  117. a device, the vector entry should contain the entry EMULATE. This will be
  118. patched at load time to contain a jump to the Kernel's emulation routine.
  119. These routines will emulate the action of the vector by breaking down the
  120. request into simpler primitives. For example, if the hardware has the
  121. functionality to draw arc, the arc vector will contain the address
  122. of the routine to dispatch the arc data to the hardware and would
  123. appear as follows:
  124.  
  125.     dw    offset    ARC        ; Vector to the arc routine
  126.  
  127. If, as is often the case, the hardware doesn't have the functionality to
  128. display arcs, the vector would instead contain the EMULATE vector:
  129.  
  130.     dw    EMULATE
  131.  
  132. The Kernel has emulation support for the following vectors:
  133.  
  134.     BAR        Filling 3D rectangles
  135.     ARC        Elliptical arc rendering
  136.     PIESLICE    Elliptical pie slices
  137.     FILLED_ELLIPSE    Filled Ellipses
  138.  
  139. The Driver Status Table
  140. =======================
  141.  
  142. BGI requires that each driver contain a Driver Status Table (DST) to
  143. determine the basic characteristics of the device that the driver
  144. addresses. As an example, the DST for a CGA display is shown here:
  145.  
  146. STATUS STRUC
  147. STAT    DB    0        ; Current Device Status (0 = No Errors)
  148. DEVTYP    DB    0        ; Device Type Identifier (must be 0)
  149. XRES    DW    639        ; Device Full Resolution in X Direction
  150. YRES    DW    199        ; Device Full Resolution in Y Direction
  151. XEFRES    DW    639        ; Device Effective X Resolution
  152. YEFRES    DW    199        ; Device Effective Y Resolution
  153. XINCH    DW    9000        ; Device X Size in inches*1000
  154. YINCH    DW    7000        ; Device Y Size in inches*1000
  155. ASPEC    DW    4500        ; Aspect Ratio = (y_size/x_size) * 10000
  156.     DB    8h
  157.     DB    8h        ; for compatibility, use these values
  158.     DB    90h
  159.     DB    90h
  160. STATUS    ENDS
  161.  
  162. The BGI interface provides a system for reporting errors to the BGI Kernel
  163. and to the higher level code developed using Borland's language packages.
  164. This is done using the STAT field of the Driver Status Table. This field
  165. should be filled in by the driver code if an error is detected during the
  166. execution of the device installation (INSTALL). The following error codes
  167. are predefined in include file GRAPHICS.H for Turbo C and in the Graphics
  168. unit for Turbo Pascal.
  169.  
  170.    grOk              =   0    Normal Operation, No errors
  171.    grNoInitGraph      =  -1
  172.    grNotDetected      =  -2
  173.    grFileNotFound     =  -3
  174.    grInvalidDriver    =  -4
  175.    grNoLoadMem          =  -5
  176.    grNoScanMem          =  -6
  177.    grNoFloodMem       =  -7
  178.    grFontNotFound     =  -8
  179.    grNoFontMem          =  -9
  180.    grInvalidMode      = -10
  181.    grError          = -11    Generic Driver Error
  182.    grIOerror          = -12
  183.    grInvalidFont      = -13
  184.    grInvalidFontNum   = -14
  185.    grInvalidDeviceNum = -15
  186.  
  187. The next field in the Device Status Table, DEVTYP, describes the class of
  188. the device that the driver controls; for screen devices, this value is
  189. always 0.
  190.  
  191. The next four fields, XRES, YRES, XEFRES, and YEFRES contain the number of
  192. pixels available to BGI on this device in the horizontal and vertical
  193. dimensions, minus one. For screen devices, XRES=XEFRES and YRES=YEFRES.
  194. The XINCH and YINCH fields are the number of inches horizontally and
  195. vertically into which the device's pixels are mapped, times 1000. These
  196. fields in conjunction with XRES and YRES permit device resolution (DPI, or
  197. dots per inch) calculation.
  198.  
  199.     Horizontal resolution (DPI) = (XRES+1) / (XINCH/1000)
  200.     Vertical resolution (DPI)  = (YRES+1) / (YINCH/1000)
  201.  
  202. The ASPEC (aspect ratio) field is effectively a multiplier/divisor pair
  203. (the divisor is always 10000) that is applied to Y coordinate values to
  204. produce aspect-ratio adjusted images (e.g., round circles). For example,
  205. an ASPEC field of 4500 implies that the application will have to transform
  206. Y coordinates by the ratio 4500/10000 when drawing circles to that device
  207. if it expects them to be round. Individual monitor variations may require
  208. an additional adjustment by the application.
  209.  
  210.  
  211. The Device Driver Vector Table
  212. ============================